<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>Installing the EJAM R package • EJAM</title>
<!-- favicons --><link rel="icon" type="image/png" sizes="16x16" href="../favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="../favicon-32x32.png">
<link rel="apple-touch-icon" type="image/png" sizes="180x180" href="../apple-touch-icon.png">
<link rel="apple-touch-icon" type="image/png" sizes="120x120" href="../apple-touch-icon-120x120.png">
<link rel="apple-touch-icon" type="image/png" sizes="76x76" href="../apple-touch-icon-76x76.png">
<link rel="apple-touch-icon" type="image/png" sizes="60x60" href="../apple-touch-icon-60x60.png">
<script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet">
<script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.4.2/css/all.min.css" rel="stylesheet">
<link href="../deps/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet">
<script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Installing the EJAM R package">
<meta name="description" content="1. Installing the EJAM R package">
<meta property="og:description" content="1. Installing the EJAM R package">
<meta property="og:image" content="https://usepa.github.io/EJAM/logo.svg">
</head>
<body>
    <a href="#main" class="visually-hidden-focusable">Skip to contents</a>


    <nav class="navbar navbar-expand-lg fixed-top bg-light" data-bs-theme="light" aria-label="Site navigation"><div class="container">

    <a class="navbar-brand me-2" href="../index.html">EJAM</a>

    <small class="nav-text text-warning me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Released version">2.32.0</small>


    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>

    <div id="navbar" class="collapse navbar-collapse ms-3">
      <ul class="navbar-nav me-auto">
<li class="nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
<li class="active nav-item dropdown">
  <button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
  <ul class="dropdown-menu" aria-labelledby="dropdown-articles">
<li><hr class="dropdown-divider"></li>
    <li><h6 class="dropdown-header" data-toc-skip>Overview for EJAM Users</h6></li>
    <li><a class="dropdown-item" href="../articles/0_whatis.html">What is EJAM</a></li>
    <li><a class="dropdown-item" href="../articles/0_webapp.html">Using EJAM</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><h6 class="dropdown-header" data-toc-skip>For analysts using R</h6></li>
    <li><a class="dropdown-item" href="../articles/1_installing.html">Installing the EJAM R package</a></li>
    <li><a class="dropdown-item" href="../articles/2_quickstart.html">Quick Start Guide</a></li>
    <li><a class="dropdown-item" href="../articles/3_analyzing.html">Basics of Using EJAM for Analysis in RStudio</a></li>
    <li><a class="dropdown-item" href="../articles/4_advanced.html">Advanced Features</a></li>
  </ul>
</li>
<li class="nav-item"><a class="nav-link" href="../news/index.html">Changelog</a></li>
      </ul>
<ul class="navbar-nav">
<li class="nav-item"><form class="form-inline" role="search">
 <input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json">
</form></li>
      </ul>
</div>


  </div>
</nav><div class="container template-article">




<div class="row">
  <main id="main" class="col-md-9"><div class="page-header">
      <img src="../logo.svg" class="logo" alt=""><h1>Installing the EJAM R package</h1>
            
      
      <small class="dont-index">Source: <a href="https://github.com/USEPA/EJAM/blob/HEAD/vignettes/1_installing.Rmd" class="external-link"><code>vignettes/1_installing.Rmd</code></a></small>
      <div class="d-none name"><code>1_installing.Rmd</code></div>
    </div>

    
    
<p>EJAM is not only a web app built in shiny R, it is also an R package,
using the <a href="https://thinkr-open.github.io/golem/" class="external-link uri" target="_blank" rel="noreferrer noopener" title="https://thinkr-open.github.io/golem/">golem</a> framework.</p>
<p>The package can be installed from a github repository. It can be
installed locally as an R package, and the data or functions can be used
outside of the shiny app interface, if you want to reuse data or code,
or want to do customized analysis or explore the data in R.</p>
<div class="section level2">
<h2 id="how-to-install">How to install<a class="anchor" aria-label="anchor" href="#how-to-install"></a>
</h2>
<div class="section level3">
<h3 id="try-this-first-if-you-just-want-to-use-the-package-not-clone-edit-source-code">Try this first (if you just want to use the package, not clone &amp;
edit source code)<a class="anchor" aria-label="anchor" href="#try-this-first-if-you-just-want-to-use-the-package-not-clone-edit-source-code"></a>
</h3>
<div class="sourceCode" id="cb1"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="fu"><a href="https://rdrr.io/r/base/options.html" class="external-link">options</a></span><span class="op">(</span>timeout <span class="op">=</span> <span class="fl">300</span><span class="op">)</span> <span class="co"># Just in case the download takes longer than 60 seconds</span></span>
<span><span class="kw">if</span> <span class="op">(</span><span class="op">!</span><span class="kw"><a href="https://rdrr.io/r/base/library.html" class="external-link">require</a></span><span class="op">(</span><span class="va"><a href="https://remotes.r-lib.org" class="external-link">remotes</a></span><span class="op">)</span><span class="op">)</span> <span class="op">{</span><span class="fu"><a href="https://rdrr.io/r/utils/install.packages.html" class="external-link">install.packages</a></span><span class="op">(</span><span class="st">"remotes"</span><span class="op">)</span><span class="op">}</span></span>
<span></span>
<span><span class="fu">remotes</span><span class="fu">::</span><span class="fu"><a href="https://remotes.r-lib.org/reference/install_github.html" class="external-link">install_github</a></span><span class="op">(</span><span class="st">"USEPA/EJAM-open"</span>, dependencies <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span>
<span></span>
<span><span class="kw"><a href="https://rdrr.io/r/base/library.html" class="external-link">library</a></span><span class="op">(</span><span class="va"><a href="https://usepa.github.io/EJAM">EJAM</a></span><span class="op">)</span></span></code></pre></div>
<p>You can also install it with source references and tests like
this:</p>
<div class="sourceCode" id="cb2"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="fu">remotes</span><span class="fu">::</span><span class="fu"><a href="https://remotes.r-lib.org/reference/install_github.html" class="external-link">install_github</a></span><span class="op">(</span><span class="st">"USEPA/EJAM-open"</span>, dependencies <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>          INSTALL_opts <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"--with-keep.source"</span>, <span class="st">"--install-tests"</span><span class="op">)</span><span class="op">)</span></span></code></pre></div>
<p>If install_github does not work, you can try something like this:</p>
<div class="sourceCode" id="cb3"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span></span>
<span><span class="va">x</span> <span class="op">&lt;-</span> <span class="st">"https://github.com/USEPA/EJAM-open/archive/refs/tags/v2.32-EJAM-open.tar.gz"</span></span>
<span></span>
<span><span class="fu">remotes</span><span class="fu">::</span><span class="fu"><a href="https://remotes.r-lib.org/reference/install_url.html" class="external-link">install_url</a></span><span class="op">(</span>url <span class="op">=</span> <span class="va">x</span>, dependencies <span class="op">=</span> <span class="cn">TRUE</span>, auth_token <span class="op">=</span> <span class="st">""</span><span class="op">)</span></span></code></pre></div>
<hr>
</div>
<div class="section level3">
<h3 id="if-you-need-the-full-source-code-or-want-to-buildinstall-in-rstudio-on-your-own">if you need the full source code or want to build/install in RStudio
on your own<a class="anchor" aria-label="anchor" href="#if-you-need-the-full-source-code-or-want-to-buildinstall-in-rstudio-on-your-own"></a>
</h3>
<p>The EJAM package is available as one of the <a href="https://github.com/USEPA/EJAM-open" class="external-link uri" target="_blank" rel="noreferrer noopener" title="github.com/USEPA/EJAM-open">USEPA
github</a> repositories (not on CRAN).</p>
<p>Options for getting the source package:</p>
<ol style="list-style-type: lower-alpha">
<li><p>One way to get the source package is that in RStudio you can
click New Project, Version Control, Git, and enter the repository URL.
It will download the full source package, which has additional files
related to development that you do not need if you just want to use the
package.</p></li>
<li><p>Yet another way to get the full source package is to use a
browser to go to the repository page, such as <a href="https://github.com/USEPA/EJAM-open" class="external-link uri" target="_blank" rel="noreferrer noopener" title="github.com/USEPA/EJAM-open">USEPA
github</a> and then click the green “Code” button, and download and
unzip the zip file that contains the package.</p></li>
<li><p>A third way is to Clone or Fork the package via GitHub Desktop or
from the GitHub site.</p></li>
</ol>
<p>Regardless of how you got the full source code, you would then need
to build/install the package from source on your computer using RStudio
(using the Build menu) or using the devtools package, for example.</p>
</div>
<div class="section level3">
<h3 id="for-a-repository-that-is-non-public-internal-or-private-for-epa-only">for a repository that is non-public (internal or private, for EPA
only)<a class="anchor" aria-label="anchor" href="#for-a-repository-that-is-non-public-internal-or-private-for-epa-only"></a>
</h3>
<p>If a USEPA github repository is not public, you need to be inside
EPA’s network (e.g., via VPN) and also need to get a personal access
token (PAT):</p>
<ol style="list-style-type: decimal">
<li>create a GitHub personal access token with at least ‘repo scope’
which you can do at <a href="https://github.com/settings/tokens" class="external-link uri">https://github.com/settings/tokens</a>
</li>
</ol>
<ul>
<li><p>For background on this, see <a href="https://usethis.r-lib.org/articles/git-credentials.html#tldr-use-https-2fa-and-a-github-personal-access-token" class="external-link uri" target="_blank" rel="noreferrer noopener">https://usethis.r-lib.org/articles/git-credentials.html#tldr-use-https-2fa-and-a-github-personal-access-token</a></p></li>
<li><p>Go to <a href="https://github.com/settings/tokens" class="external-link uri" target="_blank" rel="noreferrer noopener">https://github.com/settings/tokens</a> and
select Tokens (classic) on the left-hand side. Then click ‘Generate New
Token’ -&gt; Generate new token (classic).</p></li>
<li><p>Give it a name and select all boxes under repo scope. Scroll down
and click ‘Generate Token’.</p></li>
</ul>
<ol start="2" style="list-style-type: decimal">
<li>save GitHub credentials via Rstudio</li>
</ol>
<ul>
<li>one-time login: from the console, run
<code><a href="https://docs.ropensci.org/credentials/reference/set_github_pat.html" class="external-link">credentials::set_github_pat()</a></code>. Paste in your PAT to the
login popup under ‘Token’. This will save the PAT in your GITHUB_PAT
environmental variable, where <code><a href="https://remotes.r-lib.org/reference/install_github.html" class="external-link">remotes::install_github()</a></code> or
<code><a href="https://remotes.r-lib.org/reference/install_github.html" class="external-link">devtools::install_github()</a></code> will by default look for
it.</li>
</ul>
<ol start="3" style="list-style-type: decimal">
<li>Try to install the package using
<code><a href="https://remotes.r-lib.org/reference/install_github.html" class="external-link">devtools::install_github()</a></code>
</li>
</ol>
<div class="section level4">
<h4 id="cran-packages-needed-dependencies">CRAN packages needed (dependencies)<a class="anchor" aria-label="anchor" href="#cran-packages-needed-dependencies"></a>
</h4>
<p>EJAM needs a number of other packages to be installed that are
available from CRAN. Trying to load and attach EJAM with require(EJAM)
or library(EJAM) will alert you to those other packages you need to
install if you don’t already have them. The list of CRAN packages needed
is in the <code>DESCRIPTION</code> file in the R package source code
root folder (as can be found in the code repository). Note some are in
Suggests and you might want to install those as well – using
dependencies=T in install_github() or install_url() will make sure of
that.</p>
</div>
</div>
</div>
<div class="section level2">
<h2 id="initialize-loadattach-package">Initialize: load/attach package<a class="anchor" aria-label="anchor" href="#initialize-loadattach-package"></a>
</h2>
<p>Once the right R packages are installed, to use EJAM in the console
you can start by loading and attaching the package, using library or
require. It should automatically download some data and build an
index.</p>
<div class="sourceCode" id="cb4"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span></span>
<span><span class="kw"><a href="https://rdrr.io/r/base/library.html" class="external-link">require</a></span><span class="op">(</span><span class="va"><a href="https://usepa.github.io/EJAM">EJAM</a></span><span class="op">)</span></span></code></pre></div>
<p><strong>That should be all you need to do.</strong></p>
<hr>
<p>Just in case you need more details on how that works, the following
describes the code used by the package to get the data and build an
index.</p>
<div class="section level3">
<h3 id="details-on-the-automatic-data-downloads">Details on the automatic data downloads<a class="anchor" aria-label="anchor" href="#details-on-the-automatic-data-downloads"></a>
</h3>
<p>To work in the RStudio console, EJAM needs some datasets not stored
as part of the package. However, they already should be downloaded and
loaded into memory automatically as soon as you use
<code><a href="https://usepa.github.io/EJAM">require(EJAM)</a></code>.</p>
<p>Typically you would not need to download any datasets yourself,
because EJAM just downloads these when the app starts (technically, when
the R package is attached) (or only as needed in the case of certain
datasets that are not always needed). Some datasets are installed along
with the package, such as the [blockgroupstats] data. But large files
like “[blockpoints]” are stored on a “pins board” server and EJAM
downloads them from there. You might want your own local copies, though,
for these reasons:</p>
<p>Attaching the package actually checks for copies in memory first
(e.g., <code>exists("quaddata", envir = globalenv())</code>), then local
disk (using [dataload_from_local()] looking in the data folder of the
(source or installed) package, as defined by
<code>EJAM:::app_sys()</code> which is just a wrapper for
<code><a href="https://rdrr.io/r/base/system.file.html" class="external-link">system.file()</a></code>), then finally tries to download any still
needed, using [dataload_from_pins()] for example.</p>
</div>
<div class="section level3">
<h3 id="details-on-the-indexing-of-blocks">Details on the indexing of blocks<a class="anchor" aria-label="anchor" href="#details-on-the-indexing-of-blocks"></a>
</h3>
<p>EJAM also needs to build the index of about 8 million US block
locations (one internal point for each block), which takes a few
seconds. EJAM does this automatically when attached via
<code><a href="https://usepa.github.io/EJAM">require(EJAM)</a></code> or <code><a href="https://usepa.github.io/EJAM">library(EJAM)</a></code>, by creating an
object called <a href="../reference/localtree.html">localtree</a> based
on the <a href="../reference/quaddata.html">quaddata</a> object obtained
as mentioned above. Some functions check for it and try to build the
index on the fly if it is missing. You can also (re)build it
manually:</p>
<div class="sourceCode" id="cb5"><pre class="downlit sourceCode r">
<code class="sourceCode R"><span><span class="fu"><a href="../reference/indexblocks.html">indexblocks</a></span><span class="op">(</span><span class="op">)</span></span></code></pre></div>
</div>
</div>
  </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
    </nav></aside>
</div>



    <footer><div class="pkgdown-footer-left">
  <p>US EPA 2025</p>
</div>

<div class="pkgdown-footer-right">
  <p>EJAM Version 2.32.0</p>
</div>

    </footer>
</div>





  </body>
</html>
